view release on metacpan or  search on metacpan

Agent.pm  view on Meta::CPAN

  my $a = new Agent( Name => 'path_to_agent.pa', %args );

  $a->run();

=head1 DESCRIPTION

Agent Perl is meant to be a multi-platform interface for writing and using
transportable perl agents.

=over 4

=item A Perl Agent

Is any chunk of Perl code that can accomplish some user-defined objective
by communicating with other agents, and manipulating any data it obtains.

A Perl Agent consists of a knowledge base (variables), a reasoning
procedure (code), and access to one or more languages coupled with
methods of communication.  These languages remain largely undefined, or
rather, user-defined; support for KQML/KIF is under development.

=item Developing An Agent

Note that the developer must devise the reasoning procedure and knowledge
base described above.  Agent Perl does not place any restrictions on what
you may do; it only tries to make the 'doing' part easier.

An agent is written as an inheriting sub-class of I<Agent>.  Each agent's
class should be stored in a '.pa' file (I<p>erl I<a>gent), and must contain
an C<agent_main()> method.  All agents are objects.  See the examples for
more details, and learn how Agent.pm works so you won't step on its toes!

=back

=head1 CONVENTIONS

I<Arguments> to subroutines are passed in hashes unless otherwise noted.

Capital-a I<Agent> refers to C<Agent.pm> unless the context is obvious.
Lowercase I<agent> refers to I<an> agent.

=head1 CONSTRUCTOR

=over 4

=item new()

Creates a new agent object.  You must tell new() where to get
the agent by passing in I<one> of the following arguments (in a hash):

I<Stored>: The agent stored in a Tom object.

I<File>: An IO::Handle (or any subclass) file handle from which the
agent can be read.

I<Name>: The agent's name.  This prompts new to search @INC and './'
for the agent's '.pa' source file.

I<Code>: The agent's source code.

These are listed in order of precedence.  To handle security issues,
new() also groks this argument:

I<Compartment>: A Safe Compartment within which the agent will be
registered, and later executed.  See the C<Safe> pod for details.

Developers should note that these keywords are I<reserved>.  Any additional
arguments are passed to the agent being created.

=back

=head1 METHODS

=over 4

=item store()

Returns the agent object in stringified form, suitable for network
transfer or storage.

=item run()

Executes the agent.  If the I<Thread> argument is passed and your system has
Thread.pm, run() tries to execute the agent in an asynchronous thread via
Thread's async() command (see the Thread pod for more details).  Additional
arguments are passed to the agent being run.

=item identity()

Returns a unique string identifying the agent I<in its present state>.

=back

=head1 SEE ALSO

C<Agent::Message> and C<Agent::Transport> for agent developers.

=head1 AUTHOR

Steve Purkis E<lt>F<spurkis@engsoc.carleton.ca>E<gt>

=head1 COPYRIGHT

Copyright (c) 1997, 1998 Steve Purkis.  All rights reserved.  This package
is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.

=head1 THANKS

James Duncan for the C<Tom> module and I<many> ideas; the people of the 
Perl5-Agents mailing list for their support.

=cut