diff --git a/docs/aea-vs-mvc.md b/docs/aea-vs-mvc.md index 5b34cbd149..605f6bcbb3 100644 --- a/docs/aea-vs-mvc.md +++ b/docs/aea-vs-mvc.md @@ -20,11 +20,3 @@ The AEA framework is based on The `View` concept is probably best compared to the `Message` of a given `Protocol` in the AEA framework. Whilst views represent information to the client, messages represent information sent to other agents, other agent components and services. - -## Next steps - -We recommend you continue with the next step in the 'Getting Started' series: - -- Build a skill for an AEA - -
diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index f852eab46f..0000000000 --- a/docs/index.md +++ /dev/null @@ -1,62 +0,0 @@ - -The AEA framework provides the tools for creating Autonomous Economic Agents (AEA). - -## What are AEAs? - -We define an autonomous economic agent or AEA as: - -> An intelligent agent acting on an owner's behalf, with limited or no interference, and whose goal is to generate economic value for its owner. - - - -An AEA represents an individual, organisation or object and looks after its interests. AEAs act independently of constant input from their owner and autonomously execute actions to achieve their prescribed goals. Their purpose is to create economic value for you, their owner, in clearly defined domains. AEAs have a wide range of application areas and we provide demo guides to highlight examples of their use cases. - -### What is not an AEA - -* Any agent: AEAs' purpose is to generate economic value in a multi-stakeholder environment with competing incentives between agents. They represent humans, organisations or objects. -* APIs or sensors which do not have agency. -* Smart contracts which do not display any proactiveness and are purely reactive to external requests (=contract calls and transactions). -* Artificial General Intelligence (AGI). AEAs can have a very narrow, goal directed focus involving some economic gain and can have a very simple logic. - -
-

Note

-

In the rest of the documentation, unless specified otherwise, we use the terms AEA and agent interchangeably to refer to AEA as defined above.

-
- -## What is the AEA Framework? - -The AEA framework is a development suite, currently implemented in Python, which equips you with an efficient and accessible set of tools for building and running AEAs. The framework is modular, extensible, and composable. It attempts to make agent development as straightforward an experience as possible, similar to web development using popular web frameworks. - -AEAs achieve their goals with the help of a search & discovery service for AEAs -- the simple Open Economic Framework (sOEF) -- a decentralized agent communication system -- the Agent Communication Network (ACN) -- and using Fetch.ai's blockchain as a financial settlement and commitment layer. AEAs can also be integrated with third-party blockchains, such as Ethereum. - - -## Why build with the AEA Framework? - -The AEA framework provides the developer with a number of features, which combined cannot be found anywhere else: - -* The peer-to-peer agent communication network (ACN) allows your AEAs to interact with all other AEAs over the public internet. -* The search and discovery system sOEF allows your AEAs to find other AEAs. -* The AEA registry enables code sharing and re-use by providing a space in which AEAs or their individual components may be shared. -* The framework's crypto and ledger APIs make it possible for AEAs to interact with blockchains. -* The contract packages enable AEAs to interact with smart contracts in Fetch.ai and other third-party decentralised ledgers. - - -## Next steps - -To get started developing your own AEA, check out the getting started section. - -To learn more about some of the distinctive characteristics of agent-oriented development, check out the guide on agent-oriented development. - -If you would like to develop an AEA in a language different to Python then check out our language agnostic AEA definition. - -If you want to run a demo, check out the demo guides. - - -## Help us improve - -
-

Note

-

This developer documentation is a work in progress. If you spot any errors please open an issue on Github or contact us in the developer Discord channel.

-
- -
diff --git a/docs/interaction-protocol.md b/docs/interaction-protocol.md index 0bc3b52293..8d6129b297 100644 --- a/docs/interaction-protocol.md +++ b/docs/interaction-protocol.md @@ -29,30 +29,3 @@ In the http connection guide we demon The `fetchai/http_client` connection can be used to make requests to third party servers. In this case, a skill containing the logic for the production of http requests would create messages conforming with the `fetchai/http` protocol and sends it to the `fetchai/http_client` connection which in turn translates it into http payload and sends it to the destination server. Note that in general, third party SDKs can be wrapped in a connection and shared with other developers as a package. Often this also involves creating a custom protocol to enforce the type of interactions permitted between skills and the connection wrapping the SDK. - - -## Next steps - -### Recommended - -We recommend you continue with the next step in the 'Getting Started' series: - -- Trade between two AEAs - -### Relevant deep-dives - -Most AEA development focuses on developing the `Skills` and `Protocols` necessary for an AEA to deliver against its economic objectives and implement interaction protocols. - -Understanding `Protocols` is core to developing your own agent. You can learn more about the `Protocols` agents use to communicate with each other and how they are created in the following section: - -- Protocols - -Most of an AEA developer's time is spent on `Skill` development. `Skills` are the core business logic components of an AEA. Check out the following guide to learn more: - -- Skills - -In most cases, one of the available `Connection` packages can be used. Occasionally, you might develop your own `Connection`: - -- Connections - -
\ No newline at end of file diff --git a/docs/acn.md b/docs/introduction/core-concepts/how-do-aeas-create-value/acn.md similarity index 81% rename from docs/acn.md rename to docs/introduction/core-concepts/how-do-aeas-create-value/acn.md index f083aeff33..865c2102f0 100644 --- a/docs/acn.md +++ b/docs/introduction/core-concepts/how-do-aeas-create-value/acn.md @@ -1,7 +1,17 @@ +## Agent Communication Network (ACN) -The agent communication network (ACN) provides a system for agents to find each other and communicate, solely based on their wallet addresses. It addresses the message delivery problem. +ACN is a peer-to-peer communication network for agents. It allows AEAs to send and receive envelopes between each other. + +The implementation builds on the open-source libp2p library. A distributed hash table is used by all participating peers to maintain a mapping between agents' cryptographic addresses and their network addresses. + +Agents can receive messages from other agents if they are both connected to the ACN (see here for an example). + +!!! note + + Hence, the agent communication network (ACN) provides a system for agents to find each other and communicate, solely based on their wallet addresses. It addresses the message delivery problem. ## Message delivery problem + Agents need to contact each others. Given the wallet address of a target agent, how can the originator agent deliver a message to it whilst guaranteeing certain properties? The properties we would like to have are: @@ -34,7 +44,6 @@ At its core, the ACN implements a distributed hash table (DHT). A DHT is similar For the ACN, we use the DHT to store and maintain association between an agent address and the (network) location of its peer. - ## N-tier architecture To satisfy different resource constraints and flexible deployment the ACN is implemented as a multi-tier architecture. As such, it provides an extension of the client-server model. The agent framework exploits this by implementing different tiers as different `Connections`: diff --git a/docs/introduction/core-concepts/how-do-aeas-create-value/ledger.md b/docs/introduction/core-concepts/how-do-aeas-create-value/ledger.md new file mode 100644 index 0000000000..525bd7958c --- /dev/null +++ b/docs/introduction/core-concepts/how-do-aeas-create-value/ledger.md @@ -0,0 +1,19 @@ +## Ledgers + +Ledgers enable AEAs to store transactions, for example involving the transfer of funds to each other, or the execution of smart contracts. They optionally ensure the truth and integrity of agent to agent interactions. + +Whilst a ledger can, in principle, be used to store structured data (for instance, training data in a machine learning model) in most use cases the resulting costs and privacy implications do not make this an efficient use of the ledger. Instead, usually only references to structured data - often in the form of hashes - are stored on a ledger, and the actual data is stored off-chain. + +The Python implementation of the AEA Framework currently integrates with three ledgers: + +- Fetch.ai ledger +- Ethereum ledger +- Cosmos ledger + +However, the framework makes it straightforward for any developer to add support for other ledgers. + +### AEAs as second layer technology + +The following presentation discusses how AEAs can be seen as second layer technology to ledgers. + + diff --git a/docs/introduction/core-concepts/how-do-aeas-create-value/oef.md b/docs/introduction/core-concepts/how-do-aeas-create-value/oef.md new file mode 100644 index 0000000000..3037d4bfe1 --- /dev/null +++ b/docs/introduction/core-concepts/how-do-aeas-create-value/oef.md @@ -0,0 +1,20 @@ +The **Open Economic Framework (OEF)** and **Decentralized Ledger Technologies (DLTs)** allow AEAs to create value through their interaction with other AEAs. The following diagram illustrates the relation of AEAs to the OEF and DLTs. + +The AEA, OEF, and Ledger systems + +## Open Economic Framework (OEF) + +The _Open Economic Framework_ (OEF) consists of protocols, languages and market mechanisms agents use to search and find each other, communicate with as well as trade with each other. As such the OEF defines the decentralised virtual environment that supplies and supports APIs for autonomous third-party software agents, also known as Autonomous Economic Agents (AEAs). + +
+

Note

+

The OEF is under development. Expect frequent changes. What follows is a description of the current implementation.

+
+ +At present, the OEF's capabilities are fulfilled by three components: + +- a permissionless, public peer to peer (agent to agent) communication network, called the Agent Communication Network; +- a set of agent interaction protocols; and +- a centralized search and discovery system. + +The latter will be decentralized over time. diff --git a/docs/introduction/core-concepts/how-do-aeas-create-value/search-and-discovery.md b/docs/introduction/core-concepts/how-do-aeas-create-value/search-and-discovery.md new file mode 100644 index 0000000000..909170f181 --- /dev/null +++ b/docs/introduction/core-concepts/how-do-aeas-create-value/search-and-discovery.md @@ -0,0 +1,5 @@ +## Search and Discovery + +A simple OEF (sOEF) node allows agents to discover each other. In particular, agents can register themselves and the services they offer, and can search for agents who offer specific services. + +For two agents to be able to find each other, at least one must register itself on the sOEF and the other must query the sOEF node for it. diff --git a/docs/introduction/core-concepts/how-do-aeas-create-value/soef/simple-oef.md b/docs/introduction/core-concepts/how-do-aeas-create-value/soef/simple-oef.md new file mode 100644 index 0000000000..88489e0343 --- /dev/null +++ b/docs/introduction/core-concepts/how-do-aeas-create-value/soef/simple-oef.md @@ -0,0 +1,276 @@ +# Simple-OEF: Agent Search and Discovery + +This documentation has been produced for the Simple-OEF version `0.3.4`. + +## Concepts + +The Simple-OEF, or soef, is a **search and discovery** mechanism for **autonomous economic agents**. Agents register with the soef and are then able to conduct searches around them to find other agents that may be able to help. It is a relatively simple implementation focussing on functionality, performance and ease-of-use. As it develops, it will evolve into a full-scale decentralised, multi-dimensional digital world. + +The work-flow is: + +* *Find* relevant agents on the soef, +* *Communicate* using the Agent Framework's peer-to-peer network, +* *Negotiate* and then transact on the ledger in order to exchange value for tokens + +When an agent registers with the soef, it is issued with a *unique reference* which is quoted in all subsequent transactions. This way, the soef knows who its talking to. The soef is transaction based, so it does not need a permanent connection to be maintained in order to work with it. If it does not hear from an agent for a period of time, that agent will be timed out and automatically unregistered. This period of time is typically about one hour, but you can see the soef's configuration at: + +https://s-oef.fetch.ai:443 + +Agents identify themselves in a number of ways. These include their address, their given name, their classification and their genus. They can also describe how they "look" in other ways, and specify the services that they provide. + +In order to register, agents *must* provide a valid address and a given name. The address can be for the Fetch.ai native ledger, the Fetch.ai Cosmos ledger or the Ethereum ledger. It is this that uniquely identifies them, and addresses cannot be duplicated or shared. The given name can be anything and it is not used for search filtering. Typically, it can be thought of as a debugging aid or a context. Names could be Alice, Bob or Jim, as well as they could be a flight number, train identity or reference code. They *appear* in find results, but are not used to find by. + +## Describing an Agent + +Agents describe themselves in three ways: + +1. **Identity**: their address and ledger type along with their given name +2. **Personality pieces**: how they *look* +3. **Service keys**: what they *do*, *sell* or *want*. + +We cover all of these in this next section. It's important to understand the difference between personality pieces and service keys, as agents only have one appearance, but they can provide many services. Search results can be filtered by a number of both, and wildcards are permitted where relevant. + +### Personality Pieces + +Agents can have a number of personality pieces. These describe how an agent appears, where it is, and other properties such as heading, supported protocols and types of transactions. All personality pieces are optional, but **the more you set, the easier it is for searchers to narrow you down accurately**. + +| Piece | Description | +| ------------------- | ------------------------------------------------------------ | +| `genus` | Coarse type of agent, includes things such as `vehicle`, `building`, `iot`. See the genus table below. | +| `classification` | An agent's classification, typically in the form `mobility.railway.train`. See note below on classifications. No fixed classifications are specified. Classifications can contain alphanumeric characters, the period, underscore and colon (`_.:`). | +| `architecture` | Agent's architecture. See the architecture table below. Introduced in version `0.1.20`. The vast majority of agents should set this to `agentframework`. | +| `dynamics.moving` | Boolean, indicates if the agent is moving or not. | +| `dynamics.heading` | Indicates the heading of the agent, in radians, with 0.0 pointing due north. | +| `dynamics.altitude` | Altitude of the agent in metres from MSL | +| `dynamics.position` | Indicates the GPS co-ordinates of the agent as latitude and longitude. | +| `action.buyer` | Boolean, indicates whether the agent wishes to buy information, i.e., is an agent that requires value from another agent. | +| `action.seller` | Boolean, indicates whether the agent sells information, i.e., provides value. Value provided can be zero-cost. | + +#### Genus list + +A genus is a coarse agent class. It is the roughest description of what an agent is, and an easy way of filtering large groups of agents out of searches. The supported genus list is: + +| Name | Description | +| ----------- | ------------------------------------------------------------ | +| `test` | Agent is a test agent, and should be generally ignored. | +| `vehicle` | Moving objects such as trains, planes and automobiles | +| `avatar` | An agent that *represents* a human being | +| `service` | An agent that provides a service | +| `iot` | An agent that represents an Internet of Things device | +| `data` | An agent that represents data | +| `furniture` | Small fixed location items such as signs, mobile masts | +| `building` | Large fixed location item such as house, railway station, school | +| `buyer` | Indicates the agent is a buyer *only* and does not have value to deliver | +| `viewer` |The agent is a view in the world, acting as a "camera" to view content | +| `financial` |Financial agent: service, exchange, autonomous market maker, etc. | + +The best way to use genus is to pick the **best fit** choice. If there isn't one for you, then do not specify it. If you feel that a high-level genus is missing, please make the suggestion in our Developer Discord (see here). + +#### Architectures + +An architecture is a clue to other agents to describe how the agent is built. The vast majority of agents will be built using the Fetch Agent Framework, but in some cases, such as light-weight IoT devices or test/debugging, agents are built otherwise. Architecture offers a way of describing or filtering, as agents with a similar architecture are more likely to be able to communicate with each other in a meaningful way. + +| Architecture | Description | +| ---------------- | ------------------------------------- | +| `custom` | Custom agent architecture | +| `agentframework` | Built using the Fetch Agent Framework | + +#### A note on classifications + +There is currently no fixed set of guidelines as to how classifications are used. It is expected that agent builders will converge on a set of standards, and as those become clearer, they will be documented as "by convention" classification uses. Here are some examples of classifications in use: + +```bash +mobility.railway.station +mobility.railway.train +mobility.road.taxi +infrastructure.road.sign +``` + +When filtering by classifications, the `*` wildcard can be used to, for example, capture all mobility related agents with a wildcard of `mobility.*`. + +### Service Keys + +Agents can have a number of service keys. Service keys are simple key/value pairs that describe the list of services that the agent provides. Whilst personality pieces can be thought of as how an agent *looks*, service keys are what an agent *has* or *does*. Service keys are user defined and as with personality pieces, currently have no convention for formatting. They are at the agent builder's discretion. As this changes, the documentation will be updated. However, for *buyer* agents, three suggested keys are: + +```bash +buying_genus +buying_architecture +buying_classifications +data_type +si_unit +``` + +This allows searches to look for potential buyers of classifications, genus or with a compatible architecture. + +## Finding Agents + +The soef is designed for **geographic searches** where agents are able to find other agents near to them that are able to provide them with the value that they want, or who might wish to have the value they provide. However, it also allows for **positionless searches** on a single node. Future versions of the soef will support searches across nodes, and dimensional reduction-based fuzzy searches. + +Geographic searches are performed using the `find_around_me` operation. This allows searches that: + +* Are within a certain range in KM +* Optionally must be positioned within an angle of a heading +* That have a specified set of personality pieces (with wildcards where applicable) +* That have a specified set of service keys (with wildcards) +* Where chain identifiers match + +Positionless searches are performed using the `find_on_this_node` operation. This allows searches that: + +* That have a specified set of personality pieces (with wildcards where applicable) +* That have a specified set of service keys (with wildcards) +* Where chain identifiers match + +**At least one** filter must be supplied in positionless searches. Positionless searches are not boundless, they are capped at a specific number. The tighter the filters, the less likely that you will be capped. + +Some limits apply to the maximum number of filters, range and returned results. This may vary from soef instance to soef instance. You can see (and parse if required) these by getting the soef status at: + +https://s-oef.fetch.ai:443 + +The soef returns XML that includes information about all found agents. An example of that, unparsed, looks like this: + +```xml + + 1 + 1 + 0 + + + + 2h6fi8oCkMz9GCpL7EUYMHjzgdRFGmDP5V4Ls97jZpzjg523yY + + 55.7363 + + 52.5 + 0.2 + + + + +``` + +**The `` block is only returned if the agent has set itself to disclose its position in a find.** Likewise, **the `user_context=""` is only returned if enabled**. Normally, the default is not to, and agents will then only return the `` item. This is because agents may deliver their precise location as part of the value that they deliver, and therefore it would need to be negotiated and potentially paid for. However, sometimes, it is desirable for agents to always deliver their position when found but specify the accuracy. Because of this, the soef supports four levels of accuracy: + +| Level | Accuracy | +| --------- | --------------------------------------------------- | +| `none` | **Default** do *not* disclose position, range only. | +| `low` | Rounded to nearest 11km | +| `medium` | Rounded to nearest 1.1km | +| `high` | Rounded to nearest 110 metres | +| `maximum` | No rounding: supplied in maximum available detail | + +## Technical Details + +For the majority of use cases, the soef will be used from the Agent Framework. As a result, talking to it directly will not be needed. There are some occasions where interacting with the soef directly may be required, and this section documents the API functionality. + +Until version 1.0 and main-net version 2 (expected in early 2021), some of the security and paid-for-services are not implemented and where they are, they generally not enforced. Digital signatures for the sign-on process and unique identity recovery will be implemented, as will encryption on sensitive data transport, for example. Thus the API is likely to change substantially in the coming months, particularly the initial registration process. It is not recommended that you invest in substantial code that talks to the soef directly until after 1.0, and it is always preferred to go through the Agent Framework. + +### Registration + +Agents register at the `/register` page on the soef. They are expected to provide four pieces of information: + +1. An API key +2. A chain identifier, which can be either `fetchai_v1` for the Fetch native network (testnet or mainnet), `fetchai_v2_*` for the Fetch version 2 network or `ethereum` for the Ethereum network. See the "Chain identifiers" table below for a complete list of supported chain identifiers. +3. An address, which must be a valid address for the specified chain identifier +4. A "given name" (see "Concepts", above), which can be anything from Alice to Bob, or a flight number, or any other user-given context. It must not exceed 128 characters. + +If registration is successful, the soef will return a result like this: + +```xml + + 0 + 0A709D1ED170A3E96C4AC9D014BCAE30 + +oef_AEC97453A80FFFF5F11E612594585F611D1728FFCD74BBF4FE915BBBB052 + + +``` + +This indicates success and that the agent is now in the **Lobby**. The lobby is a temporary holding pen where newly registered agents wait until the negotiation is complete. If an agent does not respond and complete its registration within 60 seconds, it is removed from the lobby and registration is cancelled. + +The `` is the **unique URL** for the new agent. This must be quoted in all subsequent interactions and is how the soef identifies that specific agent. To complete registration, use the unique URL and specify the parameters: + +* `token=` with the token that was returned above and +* `command=acknowledge` + +If this works, you will receive a success response: + +```xml + + 1 + +``` + +At this point, your agent is now fully registered and can then communicate with the soef. + +Agents that do not contact the soef at least once over a specified interval will be automatically unregistered. The typical setting for this is 60 minutes. + +#### Chain identifiers + +The soef supports a selection of chain identifiers designed to allow agents to distinguish networks in searches, but also to identify the type of address used for verification purposes. + +| Chain identifier | Network | +| --------------------------------- | ------------------------------------------------------------ | +| `fetchai_v1` | Version 1 Fetch.ai network (testnet or mainnet). Versions prior to 0.2 of the soef used `fetchai` for this, which is retained for compatibility. | +| `fetchai_v2_testnet_stable` | Version 2 Fetch.ai stable testnet, also known as "Agentland". Versions prior to 0.2 of the soef used `fetchai_cosmos` which is retained for compatibility, but deprecated. | +| `fetchai_v2_testnet_incentivised` | Current incentivised testnet. Fetch.ai are running a high-reward sequence of testnets in Q4 2020 and Q1 2021 leading to V2 mainnet. | +| `fetchai_v2_misc` | Miscellaneous v2 network. These are temporary or transient testnets where there is a desire to separate the chain ID from other v2 networks. | +| `fetchai_v2_mainnet` | Fetch.ai v2 mainnet. Not yet active. | + +### Commands + +The soef has a number of commands that can be used to set or update personality pieces, manage service keys, unregister, find other agents and other operations. These commands are specified using the agent's unique URL and a `command=` parameter. There may then be other required and optional parameters for that particular command. + +| Command | Details | +| --------------------------------------- | ------------------------------------------------------------ | +| `unregister` | Unregisters the agent from the soef. The unique URL is invalidated and the agent will no longer appear in searches. No parameters. | +| `ping` | Say hello. This is for agents that have been idle for a long period of time and wish to maintain their connection. No parameters. | +| `set_personality_piece` | Sets or updates a personality piece. Specify the `piece` (see personality piece table above) and the `value`. For personality pieces with multiple values, such as `dynamics.position`, separate them with the pipe character `|`. | +| `set_service_key` | Sets or updates a service key. Specify the `key` and the `value` to assign to it. | +| `remove_service_key` | Removes an existing service key. Specify the `key`. | +| `set_find_position_disclosure_accuracy` | Sets the find disclosure accuracy. See the table in "Finding Agents", above, for the accepted values for the parameter `accuracy`. | +| `find_around_me` | Geographic finding of agents around me. This allows various filters, such as personality pieces and service keys, to be specified. See below, as this is more complex. | +| `find_on_this_node` | Positionless finding of agents on this node. Various filters such as personality pieces and service keys can narrow the search. See below for more information. | +| `set_position` | This is a direct internal mapping to `set_personality_piece` with a piece of `dynamics.position`. It existed in the earliest versions of the soef and remains as a short-cut. It expects `longitude` and `latitude` as parameters. | +| `set_declared_name` | This allows an agent's declared name to be changed after registration. It takes one parameter, `name`, to specify the replacement name. Names cannot exceed 128 characters and must not contain illegal characters. | +| `set_user_context` | Sets an **optional** user-context for an agent to what is specified in the `value` parameter. This can be optionally disclosed in `find_around_me` if enabled. See `set_disclose_user_context`, below. The user context must not contain illegal characters and is limited to 160 maximum. | +| `set_disclose_user_context` | If the `disclose` parameter is set to `true`, the optional user context is disclosed if it has been set. Default is `false`. | + +#### Find commands in detail + +`find_around_me` and `find_on_this_node` are the big commands. Ultimately, they will cost a small amount of tokens to use, depending on the size of the request, as it involves the most computing time. This provides an incentive for soef operators to maintain soef nodes that correspond to subject areas, geographic areas or both. The command has a number of parameters specifying the filtering required. For `find_around_me`, the `range_in_km` is *required*, whereas narrowing down agents to be within a certain angle of a direction is optional. This cannot exceed a certain range, typically between 50 and 75km. This, and other configuration items, are available on the soef's configuration page. There are other parameters that are optional, although for `find_on_this_node` at least one `ppfilter` or `skfilter` must be specified. The parameters are: + +| Parameter | Use | +| ------------------- | ------------------------------------------------------------ | +| `range_in_km` | Range in kilometres to include agents in results. | +| `of_heading` | Optional: if a pizza-slice type search is required, this is the direction, in degrees, with 0.0 being north. | +| `within` | Optional: if a pizza-slice search, this is the angle in degrees from the `of_heading` that is allowed. If either `of_heading` or `within` are specified, **both** must be specified. Example: `of_heading` set to 90.0 and `within` set to 30 would exclude any agents that are not within 30 degrees of direct east of the me agent. | +| `chains_must_match` | Boolean. Must be `true` or `false`. Default is `false`. If specified, this ensures that any agents returned in the search will have the same chain identifier as you. | +| `ppfilter` | Specify a personality piece filter. Multiple `ppfilter`s can be specified. Example use is: `ppfilter=dynamics.moving,true`. Wildcards can be used where relevant, e.g.: `ppfilter=classification,mobility*` will match all classifications that *start* with `mobility`, whereas `ppfilter=classification,*mobility*` will match all classifications with `mobility` anywhere in it. | +| `skfilter` | Specify a service key filter. Multiple `skfilter`s can be specified. Example use is: `skfilter=fruit,peach` which will require any returned results to have a service key of `fruit` and a value of `peach`. Wildcards can be specified, so `skfilter=fruit,pea*` will match any agent with a service key of `fruit` that starts `pea`, so `pear` and `peach` would match. | + +#### SK Filters: filter modes + +The `skfilter` parameter for `find_around_me` also supports a *mode*. Four modes are supported: + +| Mode string | Description | +| ----------- | ---------------------------------------------- | +| PS | Key must be present, and success is required | +| PF | Key must be present, and failure is required | +| OS | Only match if present, and success is required | +| OF | Only match if present, and failure is required | + +For example: + +``` +command=find_around_me&range_in_km=50&skfilter=type,fruit,PS&skfilter=size,large,OF +``` + +In this example, the key `type` must be present, and it must match to `fruit`. If the `size` key is present, and it is set to `large`, then do not match. I.e., return everything that's a fruit within 50km except where the size is large. + +## Further information + +You can find further information, or talk to us, in the #agents channel on our official developer Discord server, which you can access here. + +We welcome your feedback and strive to deliver the best decentralised search and discovery service for agents that is possible. There are many upcoming features, including the operation incentive mechanisms, additional security and encryption, active searches (where results happen without `find_around_me` being issued), non-geographic searches across one and many soef nodes and dimensional-reduction based approximate searches. + +[Docs: issue 15, `0.3.4`, `28-Dec-2020`, TWS] diff --git a/docs/oef-ledger.md b/docs/oef-ledger.md deleted file mode 100644 index 5880a21d99..0000000000 --- a/docs/oef-ledger.md +++ /dev/null @@ -1,55 +0,0 @@ - -The Open Economic Framework (OEF) and Decentralized Ledger Technologies (DLTs) allow AEAs to create value through their interaction with other AEAs. The following diagram illustrates the relation of AEAs to the OEF and DLTs. - -The AEA, OEF, and Ledger systems - -## Open Economic Framework (OEF) - -The _Open Economic Framework_ (OEF) consists of protocols, languages and market mechanisms agents use to search and find each other, communicate with as well as trade with each other. As such the OEF defines the decentralised virtual environment that supplies and supports APIs for autonomous third-party software agents, also known as Autonomous Economic Agents (AEAs). - -
-

Note

-

The OEF is under development. Expect frequent changes. What follows is a description of the current implementation.

-
- -At present, the OEF's capabilities are fulfilled by three components: - -- a permissionless, public peer to peer (agent to agent) communication network, called the Agent Communication Network; -- a set of agent interaction protocols; and -- a centralized search and discovery system. - -The latter will be decentralized over time. - -### Agent Communication Network (ACN) - -ACN is a peer-to-peer communication network for agents. It allows AEAs to send and receive envelopes between each other. - -The implementation builds on the open-source libp2p library. A distributed hash table is used by all participating peers to maintain a mapping between agents' cryptographic addresses and their network addresses. - -Agents can receive messages from other agents if they are both connected to the ACN (see here for an example). - -### Search and Discovery - -A simple OEF (sOEF) node allows agents to discover each other. In particular, agents can register themselves and the services they offer, and can search for agents who offer specific services. - -For two agents to be able to find each other, at least one must register itself on the sOEF and the other must query the sOEF node for it. Detailed documentation is provided here. - -## Ledgers - -Ledgers enable AEAs to store transactions, for example involving the transfer of funds to each other, or the execution of smart contracts. They optionally ensure the truth and integrity of agent to agent interactions. - -Whilst a ledger can, in principle, be used to store structured data (for instance, training data in a machine learning model) in most use cases the resulting costs and privacy implications do not make this an efficient use of the ledger. Instead, usually only references to structured data - often in the form of hashes - are stored on a ledger, and the actual data is stored off-chain. - -The Python implementation of the AEA Framework currently integrates with three ledgers: - -- Fetch.ai ledger -- Ethereum ledger -- Cosmos ledger - -However, the framework makes it straightforward for any developer to add support for other ledgers. - -### AEAs as second layer technology - -The following presentation discusses how AEAs can be seen as second layer technology to ledgers. - - diff --git a/docs/simple-oef.md b/docs/simple-oef.md deleted file mode 100644 index 4c4a791bc2..0000000000 --- a/docs/simple-oef.md +++ /dev/null @@ -1,3 +0,0 @@ -# Simple-OEF: Agent Search and Discovery - -The full documentation is available here. diff --git a/mkdocs.yml b/mkdocs.yml index 5f42ec3d1a..41e815d026 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,7 +13,22 @@ theme: strict: true nav: - - Introduction: 'index.md' + - Introduction: + - AEA Framework core concepts: + - How do AEAs create value?: + - Open Economic Framework (OEF): 'introduction/core-concepts/how-do-aeas-create-value/oef.md' + - Agent Communication Network (ACN): 'introduction/core-concepts/how-do-aeas-create-value/acn.md' + - ACN Internals: 'acn-internals.md' + - Search and Discovery (SOEF): 'introduction/core-concepts/how-do-aeas-create-value/search-and-discovery.md' + - Simple OEF: 'introduction/core-concepts/how-do-aeas-create-value/soef/simple-oef.md' + - Defining Data Models: 'defining-data-models.md' + - The Query Language: 'query-language.md' + - SOEF Connection: 'simple-oef-usage.md' + - Ledgers: 'introduction/core-concepts/how-do-aeas-create-value/ledger.md' + - Ledger & Crypto APIs: 'ledger-integration.md' + - Interactions between AEAs: 'interaction-protocol.md' + - AEA and web frameworks: 'aea-vs-mvc.md' + - Relationship with the Twelve-Factor App methodology: '12-factor.md' - Version: 'version.md' - Upgrading: 'upgrading.md' - Concepts: @@ -21,7 +36,6 @@ nav: - Agent-oriented development: 'agent-oriented-development.md' - Vision: 'vision.md' - Application areas: 'app-areas.md' - - Relation to OEF and Ledger: 'oef-ledger.md' - Identity: 'identity.md' - Trust minimisation: 'trust.md' - Demos: @@ -41,10 +55,8 @@ nav: - Development - Beginner: - AEA quick start: 'quickstart.md' - Core components - Part 1: 'core-components-1.md' - - AEA and web frameworks: 'aea-vs-mvc.md' - Build your first skill - search & discovery: 'skill-guide.md' - Core components - Part 2: 'core-components-2.md' - - How AEAs talk to each other - interaction protocols: 'interaction-protocol.md' - Trade between two AEAs: 'generic-skills-step-by-step.md' - Development setup: 'development-setup.md' - Development - Advanced: @@ -59,7 +71,6 @@ nav: - Create decision-maker transaction: 'decision-maker-transaction.md' - Testing Skills: 'skill-testing.md' - Deployment: 'deployment.md' - - 12-Factor app and AEAs: '12-factor.md' - Prometheus monitoring: 'prometheus.md' - Known limitations: 'known-limits.md' - Build an AEA programmatically: 'build-aea-programmatically.md' @@ -80,18 +91,9 @@ nav: - Skills: 'skill.md' - Contracts: 'contract.md' - Decision Maker: 'decision-maker.md' - - Ledger & Crypto APIs: 'ledger-integration.md' - Message routing: 'message-routing.md' - Configurations: 'config.md' - Limitations of v1: 'limits.md' - - Agent Communication: - - Agent Communication Network: 'acn.md' - - ACN Internals: 'acn-internals.md' - - Search & Discovery: - - Simple OEF: 'simple-oef.md' - - Defining Data Models: 'defining-data-models.md' - - The Query Language: 'query-language.md' - - SOEF Connection: 'simple-oef-usage.md' - Developer Interfaces: - CLI: - Installation: 'cli-how-to.md'