# Portfolio Profile Specification

|                       |                                 |
| --------------------- | ------------------------------- |
| **Identifier**        | `urn:adl:profile:portfolio:1.0` |
| **Status**            | Draft                           |
| **ADL Compatibility** | 0.3.x                           |
| **Schema**            | `schema.json`                   |
| **Dependencies**      | None                            |

## 1. Introduction[​](#1-introduction "Direct link to 1. Introduction")

The Portfolio Profile extends ADL with agent relationships and business domain membership capabilities. It enables organizations to track agent dependencies, composition hierarchies, and business domain alignment at scale.

When this profile is declared in an ADL document's `profiles` array, the document **MUST** satisfy all requirements defined in this specification.

### 1.1 Relationship to Other Profiles[​](#11-relationship-to-other-profiles "Direct link to 1.1 Relationship to Other Profiles")

The Portfolio Profile is independent of other ADL profiles:

* **Registry Profile** — Provides catalog identity and classification. Portfolio does not depend on registry — an enterprise may track portfolio relationships in a Git repository, CMDB, or spreadsheet without requiring formal registry integration.
* **Governance Profile** — Provides compliance and governance controls. Portfolio does not depend on governance — an agent can have portfolio relationships without being governed.

Organizations that need both registry and portfolio capabilities declare both profiles as siblings:

```
{

  "profiles": [

    "urn:adl:profile:registry:1.0",

    "urn:adl:profile:portfolio:1.0"

  ]

}
```

***

## 2. Additional Members[​](#2-additional-members "Direct link to 2. Additional Members")

### 2.1 relationships[​](#21-relationships "Direct link to 2.1 relationships")

**OPTIONAL.** An object containing agent dependencies and composition relationships.

| Member           | Type   | Required | Description                        |
| ---------------- | ------ | -------- | ---------------------------------- |
| depends\_on      | array  | OPTIONAL | Agent URIs this agent requires     |
| composed\_of     | array  | OPTIONAL | Sub-agent URIs (for orchestrators) |
| orchestrated\_by | string | OPTIONAL | Parent orchestrator URI            |
| peers            | array  | OPTIONAL | Related agents at same level       |

#### depends\_on[​](#depends_on "Direct link to depends_on")

When present, **MUST** be an array of strings. Each string **SHOULD** be an agent URI (e.g., `urn:adl:agent:acme:shared-tools:1.0`). Lists agents that this agent requires to function correctly.

#### composed\_of[​](#composed_of "Direct link to composed_of")

When present, **MUST** be an array of strings. Each string **SHOULD** be an agent URI. Used when this agent is an orchestrator that manages sub-agents.

#### orchestrated\_by[​](#orchestrated_by "Direct link to orchestrated_by")

When present, **MUST** be a string containing the URI of the orchestrating agent. Indicates this agent operates as part of a larger orchestrated system.

#### peers[​](#peers "Direct link to peers")

When present, **MUST** be an array of strings. Each string **SHOULD** be an agent URI. Lists agents that operate at the same level or collaborate directly with this agent.

***

### 2.2 domain[​](#22-domain "Direct link to 2.2 domain")

**OPTIONAL.** An object containing business/functional domain membership information, aligned with Domain-Driven Design (DDD) concepts.

| Member           | Type   | Required | Description                    |
| ---------------- | ------ | -------- | ------------------------------ |
| domain\_id       | string | OPTIONAL | Domain identifier              |
| subdomain        | string | OPTIONAL | Subdomain within the domain    |
| bounded\_context | string | OPTIONAL | Bounded context name           |
| role             | string | OPTIONAL | Agent's role within the domain |

#### domain\_id[​](#domain_id "Direct link to domain_id")

When present, **SHOULD** be a URI or URN identifying the business domain (e.g., `urn:domain:customer-service`).

#### subdomain[​](#subdomain "Direct link to subdomain")

When present, specifies the subdomain within the domain (e.g., "ticketing", "live-chat").

#### bounded\_context[​](#bounded_context "Direct link to bounded_context")

When present, specifies the DDD bounded context this agent belongs to.

#### role[​](#role "Direct link to role")

When present, describes the agent's role within the domain (e.g., "primary-handler", "escalation", "specialist").

***

## 3. Example[​](#3-example "Direct link to 3. Example")

Complete Example

This example demonstrates a complete agent definition using this profile.

customer-service-agent.json

```
{

  "$schema": "https://adl-spec.org/profiles/portfolio/1.0/schema.json",

  "adl_spec": "0.3.0",

  "name": "Customer Service Agent",

  "description": "Handles tier-1 customer inquiries and support requests via chat and email channels.",

  "version": "1.2.0",

  "profiles": [

    "urn:adl:profile:portfolio:1.0"

  ],

  "data_classification": {

    "sensitivity": "internal",

    "categories": [

      "pii"

    ]

  },

  "provider": {

    "name": "Acme Support",

    "url": "https://support.acme.example",

    "contact": "support-engineering@acme.example"

  },

  "model": {

    "capabilities": [

      "function_calling",

      "streaming"

    ]

  },

  "tools": [

    {

      "name": "search_knowledge_base",

      "description": "Search the knowledge base for relevant articles",

      "parameters": {

        "type": "object",

        "properties": {

          "query": {

            "type": "string"

          },

          "limit": {

            "type": "integer",

            "default": 5

          }

        },

        "required": [

          "query"

        ]

      },

      "read_only": true

    },

    {

      "name": "create_ticket",

      "description": "Create a support ticket for escalation",

      "parameters": {

        "type": "object",

        "properties": {

          "subject": {

            "type": "string"

          },

          "description": {

            "type": "string"

          },

          "priority": {

            "type": "string",

            "enum": [

              "low",

              "medium",

              "high",

              "urgent"

            ]

          },

          "customer_id": {

            "type": "string"

          }

        },

        "required": [

          "subject",

          "description",

          "customer_id"

        ]

      },

      "requires_confirmation": true

    },

    {

      "name": "get_customer_info",

      "description": "Retrieve customer information",

      "parameters": {

        "type": "object",

        "properties": {

          "customer_id": {

            "type": "string"

          }

        },

        "required": [

          "customer_id"

        ]

      },

      "read_only": true

    }

  ],

  "permissions": {

    "network": {

      "allowed_hosts": [

        "api.acme.example",

        "kb.acme.example",

        "tickets.acme.example"

      ],

      "allowed_protocols": [

        "https"

      ],

      "deny_private": true

    }

  },

  "security": {

    "authentication": {

      "type": "oauth2",

      "required": true,

      "scopes": [

        "customers:read",

        "tickets:write",

        "kb:read"

      ]

    },

    "encryption": {

      "in_transit": {

        "required": true,

        "min_version": "1.2"

      }

    }

  },

  "relationships": {

    "depends_on": [

      "urn:adl:agent:acme:knowledge-base-agent:1.0",

      "urn:adl:agent:acme:ticket-api-agent:2.0",

      "urn:adl:agent:acme:customer-data-agent:1.5"

    ],

    "orchestrated_by": "urn:adl:agent:acme:support-orchestrator:1.0",

    "peers": [

      "urn:adl:agent:acme:billing-support-agent:1.0",

      "urn:adl:agent:acme:technical-support-agent:1.0",

      "urn:adl:agent:acme:returns-agent:1.0"

    ]

  },

  "domain": {

    "domain_id": "urn:domain:customer-service",

    "subdomain": "inquiries",

    "bounded_context": "support-portal",

    "role": "primary-handler"

  },

  "metadata": {

    "authors": [

      {

        "name": "Support Engineering",

        "email": "support-engineering@acme.example"

      }

    ],

    "license": "Proprietary",

    "documentation": "https://docs.acme.example/agents/customer-service",

    "tags": [

      "customer-service",

      "support",

      "production"

    ]

  }

}
```

***

## 4. Validation Rules[​](#4-validation-rules "Direct link to 4. Validation Rules")

Validation Required

Implementations validating against this profile **MUST** enforce the following rules. Non-conforming documents should be rejected.

| Rule   | Description                                                         |
| ------ | ------------------------------------------------------------------- |
| PFL-01 | `relationships` or `domain` **MUST** be present (at least one)      |
| PFL-02 | `relationships.depends_on` elements **MUST** be strings if present  |
| PFL-03 | `relationships.composed_of` elements **MUST** be strings if present |
| PFL-04 | `relationships.orchestrated_by` **MUST** be a string if present     |
| PFL-05 | `relationships.peers` elements **MUST** be strings if present       |

### 4.1 Schema Validation[​](#41-schema-validation "Direct link to 4.1 Schema Validation")

The portfolio profile provides a JSON Schema (`schema.json`) that extends the base ADL schema via `allOf` composition per Section 13.1 of the core specification. The profile schema:

1. References the base ADL schema via `allOf` with `$ref`.
2. Declares all portfolio-specific members in its own `properties`.
3. Uses `anyOf` to enforce that at least one of `relationships` or `domain` is present.
4. Is an open additive mixin: it does **not** set a root `unevaluatedProperties`, so it composes with other profiles via `allOf`. Closure (`unevaluatedProperties: false`) is applied once over the composed schema per Section 13.1 of the core specification.

Validators **SHOULD** use this schema for structural validation of documents declaring the portfolio profile.

### 4.2 Profile Dependencies[​](#42-profile-dependencies "Direct link to 4.2 Profile Dependencies")

This profile has no dependencies. It **MAY** be declared alongside other profiles (e.g., registry, governance) as a sibling. See Section 13.3 of the core specification for dependency rules.

***

## 5. Use Cases[​](#5-use-cases "Direct link to 5. Use Cases")

### 5.1 Dependency Management[​](#51-dependency-management "Direct link to 5.1 Dependency Management")

The `relationships` member enables:

* Deployment order determination via `depends_on`
* Orchestrator-to-sub-agent mapping via `composed_of`
* Impact analysis when agents change
* Visualization of agent relationships

### 5.2 Domain Alignment[​](#52-domain-alignment "Direct link to 5.2 Domain Alignment")

The `domain` member enables:

* Grouping agents by business capability
* Mapping agents to bounded contexts
* Understanding agent responsibilities within domains