Environment variable A2A_AGENT_APPS not passed through during APKG build/deployment

[syumpx]

Background

PAF Core Agent (paf-core-agent) implements AI-native routing using LangGraph to intelligently route user queries to specialized A2A worker agents. The routing system requires knowledge of available agents, which can be provided through two mechanisms:

1. Static Configuration File: agents_config.json in the project root
2. Environment Variable: A2A_AGENT_APPS containing JSON array of agent configurations

The agent's agent.yaml manifest references this environment variable:

environment:
  A2A_AGENT_APPS: "${A2A_AGENT_APPS}"

Problem

When deploying PAF Core Agent to the Pixell Agent Runtime (PAR), neither configuration mechanism is available in the deployed agent:

1. ❌ agents_config.json is not included in the APKG (agent.yaml lacks include_files section)
2. ❌ A2A_AGENT_APPS environment variable is not set in the deployed agent

Evidence

Investigation of deployed agent on EC2 instance i-09dcb7f387166efd0 (us-east-2):

Agent Details:

• Agent App ID: ed8784f3-b602-481c-8701-3b6406c8fd98
• Version: 1.0.8
• Agent Path: /home/agent_8c82966883524dad_5pwbelmv/.pixell/venvs/ed8784f3-b602-481c-8701-3b6406c8fd98_*/

File System Check:

find /home/agent_8c82966883524dad_5pwbelmv -name "agents_config.json" 2>/dev/null
# Result: (empty) - File not found anywhere

Environment Variable Check:

cat /proc/$(pgrep -f "ed8784f3-b602-481c-8701-3b6406c8fd98")/environ | tr '\0' '\n' | grep A2A
# Result: A2A_PORT_RANGE=50052-50071
# Missing: A2A_AGENT_APPS

Impact

Current Behavior:
When a user sends a query like "find me 10 subreddits related to ai" that should route to the Vivid Commenter agent (4906eeb7-9959-414e-84c6-f2445822ebe4):

1. LangGraph Understand Node ✅ extracts user intent correctly
2. LangGraph Routing Node ✅ calls load_agents() to get available agents
3. load_agents() checks both sources:
   • agents_config.json → ❌ File not found
   • A2A_AGENT_APPS env var → ❌ Not set
   • Returns: [] (empty list)
4. LLM receives: "Available agents: (none)"
5. LLM routing decision: "core" (no agents to route to)
6. Result: PAF Core handles the query directly instead of routing to specialized agent

Expected Behavior:
The LLM should receive Vivid Commenter agent metadata and intelligently decide to route Reddit-related queries to that specialized agent.

Root Cause Analysis

The agent.yaml manifest correctly declares the environment variable dependency:

environment:
  A2A_AGENT_APPS: "${A2A_AGENT_APPS}"

However, the pixell-kit APKG build process appears to:

1. Not pass environment variables from the build environment into the deployed agent's runtime environment
2. Not support an include_files directive in agent.yaml to package static configuration files

Why this is happening:

• The build process likely only reads agent.yaml for entrypoint, runtime, dependencies, etc.
• Environment variables in agent.yaml may be treated as documentation rather than as variables to inject
• No mechanism exists to copy additional files (like agents_config.json) into the APKG

Proposed Solutions

Option 1: Support include_files in agent.yaml (Recommended)

Allow agents to package static configuration files:

include_files:
  - "agents_config.json"
  - "config/**/*.json"

Pros:

• Version-controlled configuration
• No external dependencies
• Works in all environments
• Explicit about what's included

Cons:

• Requires pixell-kit changes
• Increases APKG size (minimal for JSON configs)

Option 2: Pass environment variables through to deployed agents

When building/deploying an APKG, read environment variables from:

1. Build environment (e.g., GitHub Actions secrets)
2. PAR deployment configuration
3. .env file in agent directory

And inject them into the agent's runtime environment.

Pros:

• Flexible configuration per deployment
• Supports secrets management
• Standard practice in container deployments

Cons:

• Requires secure secret handling
• More complex deployment process

Option 3: Both (Recommended for Flexibility)

Support both static files and environment variable injection, allowing agents to choose the appropriate mechanism based on their needs.

Affected Components

1. pixell-kit build process - APKG assembly and packaging
2. PAR deployment - Agent runtime environment setup
3. Agent manifest schema - agent.yaml specification

Environment Variable Details

Variable Name (exact): A2A_AGENT_APPS

Expected Format:

[
  {
    "agent_app_id": "4906eeb7-9959-414e-84c6-f2445822ebe4",
    "name": "Vivid Commenter",
    "endpoint": "https://par.pixell.global/agents/4906eeb7-9959-414e-84c6-f2445822ebe4",
    "protocol": "grpc",
    "description": "AI-powered Reddit commenter...",
    "capabilities": ["Find subreddits...", "..."],
    "example_queries": ["find subreddits about AI", "..."]
  }
]

Referenced in: paf-core-agent/agent.yaml line 37

Related Issues

This issue blocks the AI-native routing feature in PAF Core Agent, making it impossible to leverage specialized worker agents in production deployments.

Request

Please investigate the pixell-kit build process and implement one or both of the proposed solutions to enable:

1. Packaging of static configuration files via include_files directive
2. Environment variable injection from build/deployment environment into agent runtime

This will unblock advanced agent orchestration features and multi-agent coordination capabilities in the Pixell ecosystem.