diff --git a/ai/gen-ai-agents/custom-rag-agent/start_ui_mcp.sh b/ai/gen-ai-agents/custom-rag-agent/start_ui_mcp.sh new file mode 100755 index 000000000..38f37f3cf --- /dev/null +++ b/ai/gen-ai-agents/custom-rag-agent/start_ui_mcp.sh @@ -0,0 +1,2 @@ +streamlit run ui_mcp_agent.py + diff --git a/ai/gen-ai-agents/mcp-oci-integration/start_aggregator.sh b/ai/gen-ai-agents/mcp-oci-integration/start_aggregator.sh new file mode 100755 index 000000000..b02bef0a4 --- /dev/null +++ b/ai/gen-ai-agents/mcp-oci-integration/start_aggregator.sh @@ -0,0 +1,2 @@ +python mcp_aggregator.py + diff --git a/ai/gen-ai-agents/mcp-oci-integration/start_mcp_consumption.sh b/ai/gen-ai-agents/mcp-oci-integration/start_mcp_consumption.sh new file mode 100755 index 000000000..859206f4a --- /dev/null +++ b/ai/gen-ai-agents/mcp-oci-integration/start_mcp_consumption.sh @@ -0,0 +1,2 @@ +python mcp_consumption.py --port 9500 + diff --git a/ai/gen-ai-agents/mcp-oci-integration/start_mcp_explorer.sh b/ai/gen-ai-agents/mcp-oci-integration/start_mcp_explorer.sh new file mode 100755 index 000000000..7f1338386 --- /dev/null +++ b/ai/gen-ai-agents/mcp-oci-integration/start_mcp_explorer.sh @@ -0,0 +1,2 @@ +streamlit run mcp_explorer.py + diff --git a/ai/gen-ai-agents/mcp-oci-integration/start_mcp_internet_search.sh b/ai/gen-ai-agents/mcp-oci-integration/start_mcp_internet_search.sh new file mode 100755 index 000000000..9c867a2b8 --- /dev/null +++ b/ai/gen-ai-agents/mcp-oci-integration/start_mcp_internet_search.sh @@ -0,0 +1,3 @@ +python mcp_internet_search.py --port 8500 + + diff --git a/ai/gen-ai-agents/open-agent-spec/LICENSE b/ai/gen-ai-agents/open-agent-spec/LICENSE new file mode 100644 index 000000000..fb2e1fcb6 --- /dev/null +++ b/ai/gen-ai-agents/open-agent-spec/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Luigi Saetta + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/ai/gen-ai-agents/open-agent-spec/README.md b/ai/gen-ai-agents/open-agent-spec/README.md new file mode 100644 index 000000000..dfddf6f6f --- /dev/null +++ b/ai/gen-ai-agents/open-agent-spec/README.md @@ -0,0 +1,141 @@ +# ๐Ÿงฉ Open Agent Specification โ€” Overview + +A **unified declarative standard for AI agents**, designed to bring interoperability across frameworks such as **LangGraph**, **AutoGen**, and **Oracle Agent Runtime**. + +> From fragmented agent frameworks to interoperable agentic systems +> ๐Ÿ“„ Source: [arXiv 2510.04173 (October 2025)](https://arxiv.org/abs/2510.04173) + +--- + +## ๐ŸŽฏ Design Objectives + +| Objective | Description | +|------------|--------------| +| **Portability & Interoperability** | Move agents seamlessly between frameworks (LangGraph, AutoGen, OCI Agent Runtime). | +| **Declarative Definition** | Define agents in YAML/JSON instead of hardcoded logic. | +| **Modularity & Composability** | Reuse flows, tools, and sub-agents. | +| **Explicit Control & Data Flow** | Clearly define how steps connect, branch, or loop. | +| **Validation & Conformance** | Built-in schema validation ensures compatibility. | +| **Multi-Agent Composition** | Enable collaboration and orchestration among agents. | + +--- + +## ๐Ÿง  Core Concepts and Components + +| Concept | Explanation | +|----------|--------------| +| **Agent** | The reasoning or conversational entity. | +| **Flow** | Structured workflow defining execution steps (nodes, branches, loops). | +| **Tool** | API, function, or service the agent can call. | +| **Memory / Prompt Templates** | Mechanisms for contextual state and conversation history. | +| **Edges** | Define relationships and data flow between nodes. | + +These building blocks form the **agent graph**, which can be executed on compatible runtimes. + +--- + +## โš™๏ธ Serialization, SDKs, and Runtime Adapters + +### Serialization Layer +- Uses **YAML/JSON schemas** for transparent, portable definitions. +- Supports versioning, validation, and interchange. + +### Python SDK โ€” `PyAgentSpec` +- Reference SDK for building, validating, and exporting agents. +- Provides schema validation, object composition, and serialization. + +### Runtime Adapters +Bridge the specification to concrete frameworks: +- **OCI Agent Runtime** +- **LangGraph** +- **AutoGen** + +Adapters support **import/export** interoperability: + +--- + +## ๐Ÿ”„ Control Flow & Data Flow Semantics + +- **Directed edges** define execution order. +- **Branching and loops** for dynamic logic. +- **Inputs/outputs** explicitly mapped between steps. +- **Nested flows** and **sub-agents** enable modular reuse. + +This model ensures predictability, traceability, and easy debugging across runtimes. + +--- + +## ๐Ÿ’ก Benefits & Value Proposition + +| Stakeholder | Benefits | +|--------------|-----------| +| **Developers** | Portability, validation, and reuse of components. | +| **Framework Vendors** | A standardized interchange format. | +| **Researchers** | Reproducibility and comparability across experiments. | +| **Enterprises** | Governance, modularity, and reduced vendor lock-in. | + +> **In essence:** โ€œWrite once, run anywhereโ€ for AI agents. + +--- + +## โš ๏ธ Limitations & Challenges + +| Challenge | Description | +|------------|--------------| +| **Early-Stage Adoption** | Specification is still experimental. | +| **Runtime Mismatch** | Execution semantics differ between frameworks. | +| **Performance Overhead** | Translation layer introduces minimal latency. | +| **Safety & Observability** | Delegated to runtime implementations. | + +--- + +## ๐Ÿ—บ๏ธ Roadmap & Future Directions + +Planned enhancements include: +- **Memory, Planning, and Datastore** extensions. +- **Agent-to-Agent (A2A)** communication protocols. +- SDKs for more languages (Java, TypeScript, Go). +- **Conformance tests** and **visual editors**. +- Community-driven **registry of agents**. + +--- + +## ๐Ÿ” Critique & Strategic Considerations + +### Strengths +- Framework-agnostic and modular. +- Promotes ecosystem collaboration. +- Declarative, composable design. + +### Risks +- Slow adoption curve. +- Runtime complexity. +- Divergent adapter implementations. + +### Recommendations +- Start small and modular. +- Contribute runtime adapters early. +- Prioritize **observability** and **safety instrumentation**. + +--- + +## ๐Ÿงพ Summary & References + +The **Open Agent Specification** defines a **declarative, interoperable schema** for building modular AI agents across multiple runtimes and ecosystems. + +| Resource | Link | +|-----------|------| +| ๐Ÿ“„ Paper | [arXiv 2510.04173](https://arxiv.org/abs/2510.04173) | +| ๐Ÿ’ป GitHub | [https://github.com/oracle/agent-spec](https://github.com/oracle/agent-spec) | +| ๐Ÿ“˜ Docs | [https://oracle.github.io/agent-spec/index.html](https://oracle.github.io/agent-spec/index.html) | +| ๐Ÿ“ฐ Blog | [Oracle AI & Data Science Blog](https://blogs.oracle.com/ai-and-datascience/post/introducing-open-agent-specification) | + +--- + +### โœ… Summary Statement + +> **Open Agent Specification** is a key step toward **standardizing AI agent design**, enabling transparent, portable, and interoperable agent systems across enterprise and open-source ecosystems. + +--- + + diff --git a/ai/gen-ai-agents/open-agent-spec/agntcy_tech_report.md b/ai/gen-ai-agents/open-agent-spec/agntcy_tech_report.md new file mode 100644 index 000000000..7b39d5dc5 --- /dev/null +++ b/ai/gen-ai-agents/open-agent-spec/agntcy_tech_report.md @@ -0,0 +1,256 @@ +# AGNTCY โ€” The Agent Internet of Things + +> **AGNTCY** is an open-source initiative under the **Linux Foundation**, building the foundational stack for an **Internet of Agents (IoA)** โ€” enabling AI agents from different vendors, environments, and frameworks to **discover, identify, communicate, and collaborate securely**. + +--- + +## ๐Ÿงญ Overview + +AGNTCY provides the **infrastructure layer** for agent interoperability โ€” much like TCP/IP did for the internet. +It defines open standards and reference implementations for: + +- **Agent discovery and directory services** +- **Verifiable identity and credentials** +- **Secure low-latency messaging** +- **Observability and evaluation** +- **Schema and capability modeling** + +Originally incubated by **Ciscoโ€™s Outshift division**, AGNTCY was **donated to the Linux Foundation (2025)** to ensure vendor neutrality and ecosystem adoption. + +--- + +## ๐Ÿ—๏ธ Technical Architecture + +AGNTCY is structured as a modular, multi-layered system: + +| Layer | Component | Description | +|-------|------------|-------------| +| **1. Discovery** | **Agent Directory Service (ADS)** | Distributed registry for publishing and discovering agent metadata, capabilities, and endpoints. | +| **2. Identity** | **Decentralized Identity Framework** | Uses DIDs and Verifiable Credentials (VCs) for agent authentication and authorization. | +| **3. Messaging** | **SLIM Protocol** (Secure Low-latency Interactive Messaging) | Defines how agents communicate interactively and securely, with multi-protocol support (A2A, MCP, etc.). | +| **4. Observability** | **Monitoring & Evaluation Layer** | End-to-end tracing, metrics, and benchmarking across multi-agent workflows. | +| **5. Schema** | **OASF (Open Agentic Schema Framework)** | Defines standardized schemas for describing agent capabilities, APIs, and metadata. | + +--- + +## โš™๏ธ Discovery & Directory Architecture + +The **Agent Directory Service (ADS)** is the cornerstone of AGNTCY. + +### Features +- Distributed, peer-to-peer directory built on a **Kademlia-like DHT** (Distributed Hash Table). +- Supports **capability-based indexing** and **content-addressable metadata**. +- Metadata is **cryptographically signed** and **verifiable**. +- Uses **OCI/ORAS registry infrastructure** to store agent artifacts. +- Provides **gRPC and Protocol Buffers APIs** for lookup, registration, and synchronization. +- Supports **federation** between multiple directory instances. + +### Workflow +1. An agent registers metadata (following OASF schema) into the directory. +2. The directory node validates, signs, and publishes the record. +3. Other agents query by capability, domain, or schema. +4. Lookup returns endpoints, credentials, and metadata pointers. + +### Example Query +```bash +agntcy dir search capability="data-analysis" +``` + +--- + +## ๐Ÿ” Identity & Credentials + +AGNTCYโ€™s **identity framework** ensures trust, provenance, and accountability between autonomous agents. + +### Core Mechanisms +- **Decentralized Identifiers (DIDs)** for agent identity. +- **Verifiable Credentials (VCs)** representing trust, capability, and roles. +- **Cryptographic keypairs** for message signing and authentication. +- **Integration with external IdPs** (Okta, Auth0, Microsoft AD) or local issuance. + +### Identity Lifecycle +1. Agent requests or is assigned a DID. +2. Agent receives VCs signed by an issuer. +3. Directory verifies identity during registration. +4. Messaging layer uses identity for mutual authentication. + +> **Open issue:** Revocation and key rotation are under development; credential lifecycle management is not yet fully standardized. + +--- + +## ๐Ÿ“ก Messaging Protocol (SLIM) + +**SLIM โ€” Secure Low-latency Interactive Messaging** +A next-generation transport protocol for interactive multi-agent communication. + +### Features +- Designed for **real-time, multi-modal messaging** (text, JSON, structured payloads). +- Built for **low-latency, encrypted** communication. +- Compatible with **existing standards**: + - **A2A (Agent-to-Agent)** protocol + - **MCP (Model Context Protocol)** +- Supports **hybrid messaging** โ€” agents can interact even if they use different protocols. +- All messages are **signed, encrypted**, and **traceable**. + +### Architecture Diagram (Simplified) + +``` +[Agent A] โ†โ†’ [SLIM Router / Gateway] โ†โ†’ [Agent B] + โ†‘ โ†‘ โ†‘ + DID Auth TLS + Signatures Identity Verify +``` + +> SLIM implementations are currently in early development; expect evolving APIs and message formats. + +--- + +## ๐Ÿ”ญ Observability & Evaluation + +AGNTCY defines **standard observability hooks** for cross-agent visibility: + +- **Distributed tracing:** Monitor request/response across agent workflows. +- **Metrics:** Measure latency, throughput, success/failure rates. +- **Logging:** Structured, identity-linked logs for compliance and debugging. +- **Evaluation:** Built-in benchmarking and behavioral scoring for agents. + +### Observability Stack +- Uses **OpenTelemetry** for tracing. +- Exports metrics to **Prometheus** or equivalent backends. +- Supports **correlation IDs** for linking events across asynchronous agents. + +> A key goal is to ensure **auditable, privacy-aware observability** โ€” maintaining accountability without exposing sensitive agent data. + +--- + +## ๐Ÿงฉ Schema Layer โ€” OASF (Open Agentic Schema Framework) + +OASF defines how agents describe themselves. + +### Highlights +- YAML/JSON schema standard for: + - Agent name, purpose, owner + - Capabilities & interfaces + - Supported modalities & APIs + - Trust attributes & compliance tags +- **Extensible:** Supports domain-specific extensions. +- **Versioned:** Maintains backward compatibility. + +### Example +```yaml +agent: + id: did:agntcy:12345 + name: "Data Insight Agent" + capabilities: + - data_query + - visualization + endpoint: https://example.org/slim + credentials: + issuer: "did:agntcy:root" + trust_level: "verified" +``` + +--- + +## ๐Ÿงฐ Development Stack & Tooling + +AGNTCYโ€™s reference implementation is **cloud-native** and primarily written in **Go**. + +### Core Technologies +| Area | Technology | +|-------|-------------| +| Language | Go (Golang) | +| API Layer | gRPC + Protocol Buffers | +| Schema | OASF (JSON/YAML) | +| Containerization | Docker, ORAS | +| Deployment | Kubernetes / kind | +| Build Tools | Taskfile, Makefile | +| Security | Sigstore, Cosign | +| Observability | OpenTelemetry, Prometheus | + +### SDKs & CLI Tools +- **`agntcy-cli`** โ€” Register, discover, and manage agents. +- **SDKs (in progress):** + - Go SDK (reference) + - Python and TypeScript bindings planned +- **Schema Tools:** + - OASF Validator + - Schema Server with hot-reload + +### Example (Agent Registration) +```bash +agntcy agent register --schema agent.yaml --sign-key mykey.pem +``` + +--- + +## โ˜๏ธ Deployment Topologies + +AGNTCY components can run in multiple environments: + +| Mode | Description | +|------|--------------| +| **Local Dev** | Single-node ADS with CLI tools (for prototyping). | +| **Cloud / K8s** | Multi-node DHT directory with federation. | +| **Hybrid Edge** | Lightweight nodes running on edge devices, syncing with core directory. | + +Each component is **containerized** and exposes health/metrics endpoints for orchestration systems. + +--- + +## ๐Ÿง  Integration & Interoperability + +AGNTCY is designed to **interoperate with existing ecosystems**, not replace them. + +Supported or targeted integrations include: + +- **OpenAI MCP** (Model Context Protocol) +- **LangChain / LangGraph agents** +- **A2A protocol** +- **OCI AI and Vector Stores** +- **OpenTelemetry / Prometheus** +- **Sigstore / Cosign** for supply chain security + +This allows enterprise agents, cloud agents, and on-device agents to coexist within a unified trust and discovery fabric. + +--- + +## โš ๏ธ Challenges & Open Questions + +| Area | Challenge | +|-------|-----------| +| **Scalability** | DHT synchronization and lookup latency under high churn. | +| **Identity Lifecycle** | Revocation, key rotation, and delegation mechanisms are immature. | +| **Schema Governance** | Maintaining OASF version compatibility across vendors. | +| **Security** | Preventing malicious agent impersonation or directory poisoning. | +| **Observability Privacy** | Balancing transparency with data protection. | +| **Ecosystem Adoption** | Network effects: utility grows only with broad adoption. | + +--- + +## ๐Ÿงฉ Repository References + +| Repo | Description | +|------|--------------| +| [github.com/agntcy/dir](https://github.com/agntcy/dir) | Agent Directory Service implementation (Go) | +| [github.com/agntcy/oasf](https://github.com/agntcy/oasf) | Open Agentic Schema Framework | +| [agntcy.org](https://agntcy.org) | Official website | +| [docs.agntcy.org](https://docs.agntcy.org) | Developer documentation | +| [Outshift Blog](https://outshift.cisco.com/blog) | Technical articles by Cisco engineers | + +--- + +## ๐Ÿงญ Conclusion + +AGNTCY is **laying the groundwork for a decentralized, interoperable Internet of Agents** โ€” combining distributed discovery, verifiable identity, and secure messaging into a coherent architecture. + +While **technically promising**, it remains **early-stage**: +- Core protocols (SLIM, OASF) are evolving. +- SDKs are limited. +- Real-world scalability and revocation handling are open issues. + +However, its **architecture, neutrality, and governance model** position it as a **credible foundation for large-scale agent ecosystems** โ€” the โ€œTCP/IP for AI Agentsโ€. + +--- + +**Last Updated:** October 2025 +**Sources:** Linux Foundation, Outshift Cisco, AGNTCY.org, ArXiv 2509.18787, GitHub repositories. diff --git a/ai/gen-ai-agents/open-agent-spec/ppt/Open_Agent_Spec_Summary.pdf b/ai/gen-ai-agents/open-agent-spec/ppt/Open_Agent_Spec_Summary.pdf new file mode 100644 index 000000000..e71bac697 Binary files /dev/null and b/ai/gen-ai-agents/open-agent-spec/ppt/Open_Agent_Spec_Summary.pdf differ diff --git a/ai/gen-ai-agents/open-agent-spec/ppt/Open_Agent_Spec_Summary.pptx b/ai/gen-ai-agents/open-agent-spec/ppt/Open_Agent_Spec_Summary.pptx new file mode 100644 index 000000000..967aec0cd Binary files /dev/null and b/ai/gen-ai-agents/open-agent-spec/ppt/Open_Agent_Spec_Summary.pptx differ