Getting Started with the Agent Packaging Standard (APS)

1. Overview

This guide provides a simple walkthrough for new contributors to install the APS CLI, create their first agent, run an example, and modify its logic.

APS introduces a packaging and execution model that allows AI agents to be packaged once and run anywhere, ensuring consistency and interoperability across runtimes.

---

2. Prerequisites

Before you begin, make sure your environment meets these requirements:

Requirement	Description
Operating System	Linux, macOS, or Windows with WSL2
Python	Version 3.9 or higher
Git	For cloning repositories and examples
Network Access	Required for pulling packages from registries

---

3. Install the APS CLI

Clone the repository and install the CLI:

# Clone the APS repository
git clone https://github.com/vedahegde60/agent-packaging-standard.git
cd agent-packaging-standard

# Install the APS CLI
pip install -e cli

Verify installation:

aps --version

Expected output:

APS CLI v0.1.0 — Agent Packaging Standard

---

4. Initialize Your First Agent

Use the CLI to scaffold a new agent:

aps init my-first-agent

This creates a directory with:

• aps/agent.yaml → manifest describing metadata and inputs/outputs
• src/<agent_name>/main.py → default implementation file
• src/<agent_name>/__init__.py → Python package initialization
• AGENT_CARD.md → agent documentation

Example structure:

my-first-agent/
├── aps/
│   └── agent.yaml
├── src/
│   └── my_first_agent/
│       ├── __init__.py
│       └── main.py
└── AGENT_CARD.md

---

5. Run the Example Agent

Try running the provided echo agent:

echo '{"text": "hello world"}' | aps run examples/echo-agent

Expected output:

{
  "status": "ok",
  "outputs": {
    "text": "hello world"
  }
}

To stream results:

echo '{"text": "stream"}' | aps run examples/echo-agent --stream

---

6. Modify Agent Logic

Open src/my_first_agent/main.py in your agent folder and change the behavior. For example:

def run(inputs):
    text = inputs.get("text", "")
    return {"text": text.upper()}

Re-run the agent:

echo '{"text": "hello world"}' | aps run my-first-agent

Output:

{
  "status": "ok",
  "outputs": {
    "text": "HELLO WORLD"
  }
}

---

7. Publishing and Retrieving Packages

APS supports registries for sharing agents.

Build and publish:

aps build my-first-agent
aps publish my-first-agent/dist/dev.my-first-agent.aps.tar.gz --registry http://localhost:8080

Retrieve and run:

aps pull dev.my-first-agent --registry http://localhost:8080
aps run dev.my-first-agent

---

8. Next Steps

Area	Description
Specification	Review the APS v0.1 Specification.
Examples	Explore sample agents in Examples.
Security	Learn about provenance and integrity in Provenance.
Contributing	See Contributing Guidelines.

---

9. Troubleshooting

Issue	Resolution
aps command not found	Ensure Python scripts path is added to your environment variables.
Manifest validation errors	Verify required fields in agent.yaml match the schema.
Registry connection issues	Check network access and registry endpoint configuration.

---

10. Contact

📬 General inquiries: contact@agentpackaging.org
🧑‍💻 Community contributions: community@agentpackaging.org

---

© 2025 Agent Packaging Standard (APS) Working Group. All rights reserved. ```

---

🔑 Key Updates Made

• Added aps init step to scaffold a new agent (your original doc skipped this).
• Simplified flow: Install → Init → Run Example → Modify Logic → Publish.
• Made troubleshooting and next steps more concise for beginners.
• Updated last_updated date to today (2025‑11‑25).

This version now matches the GitHub issue requirements and is beginner‑friendly.